home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib / tk / Preserve.man < prev    next >
Encoding:
Text File  |  1992-08-24  |  7.6 KB  |  279 lines
  1. '\"
  2. '\" Copyright 1990 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/wish/man/RCS/Preserve.man,v 1.3 91/12/06 10:39:28 ouster Exp $ SPRITE (Berkeley)
  11. '\" 
  12. .\" The definitions below are for supplemental macros used in Sprite
  13. .\" manual entries.
  14. .\"
  15. .\" .HS name section [date [version]]
  16. .\"    Replacement for .TH in other man pages.  See below for valid
  17. .\"    section names.
  18. .\"
  19. .\" .AP type name in/out [indent]
  20. .\"    Start paragraph describing an argument to a library procedure.
  21. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  22. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  23. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  24. .\"    needed;  use .AS below instead)
  25. .\"
  26. .\" .AS [type [name]]
  27. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  28. .\"    name are examples of largest possible arguments that will be passed
  29. .\"    to .AP later.  If args are omitted, default tab stops are used.
  30. .\"
  31. .\" .BS
  32. .\"    Start box enclosure.  From here until next .BE, everything will be
  33. .\"    enclosed in one large box.
  34. .\"
  35. .\" .BE
  36. .\"    End of box enclosure.
  37. .\"
  38. .\" .VS
  39. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  40. .\"    of man pages.
  41. .\"
  42. .\" .VE
  43. .\"    End of vertical sidebar.
  44. .\"
  45. .\" .DS
  46. .\"    Begin an indented unfilled display.
  47. .\"
  48. .\" .DE
  49. .\"    End of indented unfilled display.
  50. .\"
  51. '\"    # Heading for Sprite man pages
  52. .de HS
  53. .if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
  54. .if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
  55. .if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
  56. .if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
  57. .if t .wh -1.3i ^B
  58. .nr ^l \\n(.l
  59. .ad b
  60. ..
  61. '\"    # Start an argument description
  62. .de AP
  63. .ie !"\\$4"" .TP \\$4
  64. .el \{\
  65. .   ie !"\\$2"" .TP \\n()Cu
  66. .   el          .TP 15
  67. .\}
  68. .ie !"\\$3"" \{\
  69. .ta \\n()Au \\n()Bu
  70. \&\\$1    \\fI\\$2\\fP    (\\$3)
  71. .\".b
  72. .\}
  73. .el \{\
  74. .br
  75. .ie !"\\$2"" \{\
  76. \&\\$1    \\fI\\$2\\fP
  77. .\}
  78. .el \{\
  79. \&\\fI\\$1\\fP
  80. .\}
  81. .\}
  82. ..
  83. '\"    # define tabbing values for .AP
  84. .de AS
  85. .nr )A 10n
  86. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  87. .nr )B \\n()Au+15n
  88. .\"
  89. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  90. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  91. ..
  92. '\"    # BS - start boxed text
  93. '\"    # ^y = starting y location
  94. '\"    # ^b = 1
  95. .de BS
  96. .br
  97. .mk ^y
  98. .nr ^b 1u
  99. .if n .nf
  100. .if n .ti 0
  101. .if n \l'\\n(.lu\(ul'
  102. .if n .fi
  103. ..
  104. '\"    # BE - end boxed text (draw box now)
  105. .de BE
  106. .nf
  107. .ti 0
  108. .mk ^t
  109. .ie n \l'\\n(^lu\(ul'
  110. .el \{\
  111. .\"    Draw four-sided box normally, but don't draw top of
  112. .\"    box if the box started on an earlier page.
  113. .ie !\\n(^b-1 \{\
  114. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  115. .\}
  116. .el \}\
  117. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  118. .\}
  119. .\}
  120. .fi
  121. .br
  122. .nr ^b 0
  123. ..
  124. '\"    # VS - start vertical sidebar
  125. '\"    # ^Y = starting y location
  126. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  127. .de VS
  128. .mk ^Y
  129. .ie n 'mc \s12\(br\s0
  130. .el .nr ^v 1u
  131. ..
  132. '\"    # VE - end of vertical sidebar
  133. .de VE
  134. .ie n 'mc
  135. .el \{\
  136. .ev 2
  137. .nf
  138. .ti 0
  139. .mk ^t
  140. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  141. .sp -1
  142. .fi
  143. .ev
  144. .\}
  145. .nr ^v 0
  146. ..
  147. '\"    # Special macro to handle page bottom:  finish off current
  148. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  149. '\"    # page bottom macro.
  150. .de ^B
  151. .ev 2
  152. 'ti 0
  153. 'nf
  154. .mk ^t
  155. .if \\n(^b \{\
  156. .\"    Draw three-sided box if this is the box's first page,
  157. .\"    draw two sides but no top otherwise.
  158. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  159. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  160. .\}
  161. .if \\n(^v \{\
  162. .nr ^x \\n(^tu+1v-\\n(^Yu
  163. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  164. .\}
  165. .bp
  166. 'fi
  167. .ev
  168. .if \\n(^b \{\
  169. .mk ^y
  170. .nr ^b 2
  171. .\}
  172. .if \\n(^v \{\
  173. .mk ^Y
  174. .\}
  175. ..
  176. '\"    # DS - begin display
  177. .de DS
  178. .RS
  179. .nf
  180. .sp
  181. ..
  182. '\"    # DE - end display
  183. .de DE
  184. .fi
  185. .RE
  186. .sp .5
  187. ..
  188. .HS Tk_Preserve tk
  189. .BS
  190. .SH NAME
  191. Tk_Preserve, Tk_Release, Tk_EventuallyFree \- avoid freeing storage while it's being used
  192. .SH SYNOPSIS
  193. .nf
  194. \fB#include <tk.h>\fR
  195. .sp
  196. \fBTk_Preserve\fR(\fIclientData\fR)
  197. .sp
  198. \fBTk_Release\fR(\fIclientData\fR)
  199. .sp
  200. \fBTk_EventuallyFree\fR(\fIclientData, freeProc\fR)
  201. .SH ARGUMENTS
  202. .AS Tk_FreeProc clientData
  203. .AP ClientData clientData in
  204. Token describing structure to be freed or reallocated.  Usually a pointer
  205. to memory for structure.
  206. .AP Tk_FreeProc *freeProc in
  207. Procedure to invoke to free \fIclientData\fR.
  208. .BE
  209.  
  210. .SH DESCRIPTION
  211. .PP
  212. These three procedures help implement a simple reference count mechanism
  213. for managing storage.  They are designed to solve a problem
  214. having to do with widget deletion.  When a widget is deleted, its
  215. widget record (the structure holding information specific to the
  216. widget) must be returned to the storage allocator.
  217. However, it's possible that the widget record is in active use
  218. by one of the procedures on the stack at the time of the deletion.
  219. This can happen, for example, if the command associated with a button
  220. widget causes the button to be destroyed:  an X event causes an
  221. event-handling C procedure in the button to be invoked, which in
  222. turn causes the button's associated Tcl command to be executed,
  223. which in turn causes the button to be deleted, which in turn causes
  224. the button's widget record to be de-allocated.
  225. Unfortunately, when the Tcl command returns, the button's
  226. event-handling procedure will need to reference the
  227. button's widget record.
  228. Because of this, the widget record must not be freed as part of the
  229. deletion, but must be retained until the event-handling procedure has
  230. finished with it.
  231. In other situations where the widget is deleted, it may be possible
  232. to free the widget record immediately.
  233. .PP
  234. \fBTk_Preserve\fR and \fBTk_Release\fR
  235. implement short-term reference counts for their \fIclientData\fR
  236. argument.
  237. The \fIclientData\fR argument identifies an object and usually
  238. consists of the address of a structure.
  239. The reference counts guarantee that an object will not be freed
  240. until each call to \fBTk_Preserve\fR for the object has been
  241. matched by calls to \fBTk_Release\fR.
  242. There may be any number of unmatched \fBTk_Preserve\fR calls
  243. in effect at once.
  244. .PP
  245. \fBTk_EventuallyFree\fR is invoked to free up its \fIclientData\fR
  246. argument.
  247. It checks to see if there are unmatched \fBTk_Preserve\fR calls
  248. for the object.
  249. If not, then \fBTk_EventuallyFree\fR calls \fIfreeProc\fR immediately.
  250. Otherwise \fBTk_EventuallyFree\fR records the fact that \fIclientData\fR
  251. needs eventually to be freed.
  252. When all calls to \fBTk_Preserve\fR have been matched with
  253. calls to \fBTk_Release\fR then \fIfreeProc\fR will be called by
  254. \fBTk_Release\fR to do the cleanup.
  255. .PP
  256. All the work of freeing the object is carried out by \fIfreeProc\fR.
  257. \fIFreeProc\fR must have arguments and result that match the
  258. type \fBTk_FreeProc\fR:
  259. .nf
  260. .RS
  261. typedef void Tk_FreeProc(ClientData \fIclientData\fR);
  262. .RE
  263. .fi
  264. The \fIclientData\fR argument to \fIfreeProc\fR will be the
  265. same as the \fIclientData\fR argument to \fBTk_EventuallyFree\fR.
  266. .PP
  267. This mechanism can be used to solve the problem described above
  268. by placing \fBTk_Preserve\fR and \fBTk_Release\fR calls around
  269. actions that may cause undesired storage re-allocation.  The
  270. mechanism is intended only for short-term use (i.e. while procedures
  271. are pending on the stack);  it will not work efficiently as a
  272. mechanism for long-term reference counts.
  273. The implementation does not depend in any way on the internal
  274. structure of the objects being freed;  it keeps the reference
  275. counts in a separate structure.
  276.  
  277. .SH KEYWORDS
  278. free, reference count, storage
  279.